Octubre 2024

1. Documentos científicos

Documentos científicos

  • Investigadores producen: notas de laboratorio, apuntes, informes técnicos, artículos científicos…

  • Muchas tareas (con diferentes herramientas) para realizar un documento.

  • Archivo maestro (.doc) + figuras + tablas + fórmulas + resultados…

    • Algunos de estos elementos se generan con programas externos
  • Proceso de creación de documentos científicos:

Proceso de creación de documentos y artículos científicos

Proceso de creación de documentos y artículos científicos

Documentos científicos

  • El proceso de creación suele ser manual -> errores

  • Alternativa para evitarlos? Programación literaria

1.1 Programación literaria

Programación literaria

  • E. Knuth en 1984 -> programación literaria
  • Integración en un solo documento: texto formateado + resultados de código
  • Generación dinámica de documentos científicos
  • Falta de herramientas para ponerlo en práctica
  • Quarto permite automatizar y gestionar todo el proceso

1.2 Investigación reproducible

Investigación reproducible

  • Método científico: publicación de investigaciones mostrando resultados.

  • Ejemplos:

    • Eficacia de un nuevo medicamento para el tratamiento de pacientes de…
    • Comparación de la capacidad de aprendizaje de alumnos en diferentes colegios de…
    • Modelado de la evolución epidémica de una enfermedad a lo largo del tiempo en una zona geográfica…
    • Beneficios de un nuevo método quirúrgico para intervenciones de pacientes…

Investigación reproducible

  • Se confiaba en los datos, condiciones, métodos y herramientas de análisis

  • Con las herramientas actuales se pueden comprobar los resultados

    • Oncología: dpto. Biotecnología de Amgen solo pudo confirmar 6 de los 53 artículos
    • Psicología: el 73% de los investigadores tardaron más de 6 meses en responder a preguntas sobre los datos que habían utilizado.
    • Economía y finanzas: diferentes paquetes SW sobre los mismos datos, producían resultados diferentes que al aplicar la misma técnica estadística directamente sobre los datos.
  • ¡¡¡SORPRESA!!! Los resultados en áreas como Medicina no eran fiables => CRISIS DE CONFIANZA

Investigación reproducible

  • Trabajo del investigador: revisión continua de métodos y resultados

Investigación reproducible

Evolución del número de publicaciones científicas retractadas o retiradas por diversas causas.

Evolución del número de publicaciones científicas retractadas o retiradas por diversas causas.

Reproducibilidad y replicabilidad

  • Su significado depende del área en la que nos encontremos.

  • Reproducibilidad: capacidad para recuperar los resultados de un análisis, utilizando los mismos datos que el análisis original y siguiendo el mismo flujo de operaciones.

    • Se deben proporcionar todos los elementos del análisis original.
    • Si se usan las mismas herramientas, código y datos => los resultados y conclusiones deben ser iguales.
  • Replicabilida: capacidad de realizar un análisis con el mismo objetivo pero sobre datos diferentes.

    • Los resultados deben ser consistentes.

Niveles de replicabilidad

  • Según los elementos publicados por los autores y el nivel de detalle:

    • No reproducible: ya no se acepta.
    • Código o datos: código o datos públicos.
    • Código y datos: código y datos públicos.
    • Entorno de ejecución y datos enlazados: código + información necesaria para reproducirlo (paquetes sw, dependencias…).
    • Gold standard: datos públicos + limpieza y preparación de datos + código (paquetes, dependencias…) + generación de resultados.

Herramientas para la replicabilidad

  • Sistemas de control de versiones para código sw (SCV):

    • Gestionar el código: control de cambios y versiones
    • Git, Mercurial, GitHub, GitLab
    • GitHub y GitLab generan documentación, manuales, ejemplos, informes de error, integración continua, testeo de código…
    • Muy recomendables cuando intervienen varias personas
  • Virtualización de sw y contenedores:

    • Instalar y desplegar el proyecto de forma independiente.
  • Control de versiones de datos:

    • SCV para datos: controlar diferentes versiones de archivos de datos
    • DVC (Data Version Control): que versión de datos y features se han utilizado en todo momento.

Herramientas para la replicabilidad

  • Gestión de modelos y experimentos: herramientas que permiten la organización, seguimiento, comparativa y selección de los experimentos y modelos utilizados.

    • ML Flow: nos permite ajustar, evaluar y optimizar el modelo, desplegarlo en entornos de producción
    • Se pueden combinar con DV => entorno integral.
  • Creación y gestión de pipelines de procesamiento de datos:

    • Flujos de procesamiento y análisis de datos (pipelines)
    • Conjunto de pipelines = workflow
    • Apache Airflow, Perfect, Luigi

1.3 Quarto para publicaciones científicas

Quarto. Definición

  • Creación de documento dinámicos y reproducibles (informes, presentaciones, libros, sitios web, etc.)

    • texto + código + salida
  • Evolución de RMarkdown

  • Ventaja: trabajar con múltiples lenguajes (R, Python, Julia…)

Quarto. Características

  • Multiplataforma: Windows, MacOS y Linux
  • Basado en Markdown: facilita la lectura y escritura
  • Diversos formatos de salida: HTML, PDF, Word, EPUB, presentaciones, LaTeX, Jupyter Notebooks…
  • Diversos lenguajes de programación: facilita la salida de datos y su visualización
  • Facilidades de edición: citas bibliográficas, referencias cruzadas, figuras, tablas…

Creación de contenido

  • Proceso para componer un documento

1.4 Instalación de Quarto

Pasos para la instalación

2. Tipos de documentos

Tipos de documentos

  • Documentos individuales:

    • Documento más sencillo
    • Combina texto con secciones de código (chunks)
    • Procesar datos, analizar y mostrar resultados.
    • Gráficos, tablas, ecuaciones, referencias bibliográficas

Tipos de documentos

  • Documentos individuales:

    • Estructura

Tipos de documentos

Tipos de documentos

  • Libros:

    • Colección de documentos.

    • Quarto books: libros estructurados en capítulos y secciones.

      • En html: portada y capítulos en html´s diferentes
      • En pdf: un único pdf
  • Artículos y publicaciones

    • rticles: plantillas para generar artículos científicos
  • Presentaciones

Tipos de documentos

Tipos de documentos

  • Dashboards

    • Herramienta para la gestión de información (monitorizar datos, analizar modelos y resultados, tomar deciones)
    • Shiny: crear aplicaciones interactivas
    • Documentción dashboard Quarto

3 Proceso de trabajo

Cadena de montaje

Producir HTML

  • Opción por defecto de salida en Quarto.

  • Se puede visualizar en cualquier navegador.

  • Ventajas:

    • El receptor no necesita tener instalado ningún sw específico
    • Fácil de publicar estos documentos en la Web utilizando alguna plataforma como Quarto Pub.

Producir PDF

  • Opción muy utilizada
  • Se añade un último paso con el motor XeLaTeX
  • Imprescindible tener instalada una distribución TeX/LaTeX en nuestro equipo
  • Plantillas de paquetes LaTeX koma-script.

4. Documentos individuales

4.1 Creación de un documento con RStudio

Creación

  • Documento individual = documento autocontenido

    texto formateado + código ejecutable

  • Necesarios los paquetes:

Creación

4.2 Estructura del documento

Estructura

Estructura

  • Opciones de salida HTML: configuración de título, subtítulo, fecha, autor, tema o estilos avanzados de HTML, numeración y tabla de contenidos, etc.

Opciones básicas para HTML con Quarto

Lista completa de opciones HTML con Quarto

  • Opciones de salida PDF:

    • Podemos configurar muchos parámetros (similares a las de HTML)
    • Interesante formato de documento LaTeX (documentclass)
    • Importante indicar el tamaño de salida (A4)
    • Para el formato de las citas -> motor BibLaTeX
    • Importante indicar el motor de compilación. Ejem: XeLaTeX (flexibilidad total en la maquetación del documento)

Opciones básicas para PDF con Quarto

Lista compelta de opciones disponibles en PDF con Quarto

Sintáxis Markdown

  • Markdown: lenguaje de marcado
  • Permite formatear texto plano de manera rápida y sencilla
  • Creado por John Gruber en 2004
  • Guía básica

Sintaxis Markdown

  • Encabezados: se crean con la almuhadilla

Sintaxis Markdown

  • Énfasis:

    • negrita -> ** o __
    • cursiva -> * o _
    • Varias opciones de cuadros para resaltar texto

Sintaxis Markdown

Sintaxis Markdown

Sintaxis Markdown

  • Listas: con - o *

    • Numéricas: 1., 2., … (cualquier número, Markdown se encarga de numerarlas)
    • Alfabéticas: a., b., …

Sintaxis Markdown

  • Tablas:

    • | separar columnas
    • - seprar filas
    • :- alinear a la izquierda
    • -: alinear a la derecha
    • :-: centrar.
    • Debajo de la tabla: : Caption {#tbl-etiqueta .(efectos)}

Sintaxis Markdown

Sintaxis Markdown

  • Imágenes o figuras:

    -![Texto si la imagen no carga](ruta-imagen)

    • Escalar: ![Texto si la imagen no carga](ruta-imagen){width=w height=h}
    • Alinear: ![Texto si la imagen no carga](ruta-imagen){fig-align="right"}. Por defecto, centrada.
    • Referencia de imágenes: ![Texto si la imagen no carga](ruta-imagen){#etiqueta}

Sintaxis Markdown

Sintaxis Markdown

Sintaxis Markdown

Sintaxis Markdown

Sintaxis Markdown

  • Fórmulas:

    • En línea: $formula$
    • Desplegadas: $$formula$$
    • Numeración de fórmulas

4.3 Creación del documento (output)

Previsualización

  • Formato salida:

    • HTML por defecto

    • Varios formatos simultáneos.

      • Opciones de configuración para cada uno de ellos
  • Render

  • Por defecto: navegador web o panel de RStudio

  • Podemos cambiarlo

Seleccionar el tipo de documento

  • Por defecto: HTML
  • Un formato de salida o varios -> elegir en Render

Opciones básicas de configuración

  • Todos los recursos del documento integrados en el HTML: embed-resources: true

4.4 Chunks de código ejecutable

Chunks

  • Cuadros de código

  • Los resultados se integran en el documento

    • Con el código actualizado, se generan los resultados correctos
  • Soporte para varios lenguajes

Chunk.Sintaxis Markdown

  • Configuraciones de salida para los chunks:

    • #| echo: false: no se muestra el código
    • #| eval: false: no se evalua el código
    • #| error: false: no se muestran los errores
    • #| warning: false: no se muestran las advertencias
    • #| output: false: no se muestra la salida
    • #| label: etiqueta: asocia etiqueta al bloque de código y se puede referenciar
    • #| fig-cap: texto: añade un pie de texto al resultado
    • #| cache: true: guarda en cache los resultados
    • #| message: true: se incluyen los mensajes de información generados
    • Además para R: #|fig-width: ancho y #|fig-height: alto

Chunk.Sintaxis Markdown

  • Opciones de configuración para las figuras

    • fig-width: ancho de la figura
    • fig-height: alto de la figura
    • fig-cap: caption de la figura
    • fig-alt: texto alternativo
    • fig-dpi: resolución de la figura

4.5 Herrramientas para el autor

Secciones del documento

  • Numerar secciones e incorporar tabla de contenido

  • Incluir referencias cruzadas
  1. Añadir etiqueta

## Título de seccion {#sec-etiqueta}

  1. Añadir referencia

En el texto añadimo una referencia a la @sec-etiqueta

  • Escluir una sección del esquema de numeración

    ## Título de seccion {.unnumbered}

Secciones del documento

  • Más opciones para las gestión de secciones:

    • anchor-sections: enlace de anclado cuando se pasa el ratón por encima
    • toc-depth: hasta que nivel de profundidad de la numeración aparece
    • toc-location: body | left | right | left-body | right-body: ubicación en la está la tabla.
    • toc-title: título de tabla
    • toc-expand: expandir o no
    • number-depth: profundidad máxima de numeración de las secciones (en consonancia con toc-depth)
    • number-offsetp: ajustar el número por el que se empieza

Citas bibliográficas y estilos

  • Gestión de refernecias bibliográficas en BibTeX
  • También se puede incluir un fichero CLS que defina un formato estándar (APA)

  • Estilo general del documento

Lista de estilos